Using the Callback Method

This section contains information that applies to both Windows and Linux.

The callback method of event notification is used when an immediate response to an event is required. To use the callback method for receiving notification that an event has occurred, you must do the following.

Install an event handler with the viInstallHandler function
Enable one or several events with the viEnableEvent function

When the enabled event occurs, the installed event handler is called.

Example: Using the Callback Method

This example shows one way you can use the callback method.

ViStatus _VI_FUNCH my_handler (ViSession vi,

ViEventType eventType, ViEvent context, ViAddr usrHandle) {

/* your event handling code here */

return VI_SUCCESS;

}

main(){

ViSession vi;

ViAddr addr=0;

.

.

viInstallHandler(vi, VI_EVENT_SERVICE_REQ, my_handler, addr);

viEnableEvent(vi, VI_EVENT_SERVICE_REQ, VI_HNDLR, VI_NULL);

.

/* your code here */

.

viDisableEvent(vi, VI_EVENT_SERVICE_REQ, VI_HNDLR);

viUninstallHandler(vi, VI_EVENT_SERVICE_REQ, my_handler, addr);

.

}

Installing Handlers

VISA allows applications to install multiple handlers for an event type on the same session. Multiple handlers can be installed through multiple invocations of the viInstallHandler operation, where each invocation adds to the previous list of handlers.

If more than one handler is installed for an event type, each of the handlers is invoked on every occurrence of the specified event(s). VISA specifies that the handlers are invoked in Last In First Out (LIFO) order. Use the following function when installing an event handler:

viInstallHandler(vi, eventType, handler, userHandle);

These parameters are defined as follows.

Parameter	Description
vi	The session on which the handler will be installed.
eventType	The event type that will activate the handler.
handler	The name of the handler to be called.
userHandle	A user value that uniquely identifies the handler for the specified event type.

The userHandle parameter allows you to assign a value to be used with the handler on the specified session. Thus, you can install the same handler for the same event type on several sessions with different userHandle values. The same handler is called for the specified event type.

However, the value passed to userHandle is different. Therefore the handlers are uniquely identified by the combination of the handler and the userHandle. This may be useful when you need a different handling method depending on the userHandle.

Example: Installing an Event Handler

This example shows how to install an event handler to call my_handler when a Service Request occurs. Note that VI_EVENT_SERVICE_REQ must also be an enabled event with the viEnableEvent function for the service request event to be delivered.

viInstallHandler(vi, VI_EVENT_SERVICE_REQ, my_handler, addr);

Use the viUninstallHandler function to uninstall a specific handler, or you can use wildcards (VI_ANY_HNDLR in the handler parameter) to uninstall groups of handlers. See viUninstallHandler for more details on this function.

Writing the Handler

The handler installed needs to be written by the programmer. The event handler typically reads an associated attribute and performs some sort of action. See the event handler in the example program later in this topic.

Enabling Events

Before an event can be delivered, it must be enabled using the viEnableEvent function. This function causes the application to be notified when the enabled event has occurred, where the parameters are:

viEnableEvent(vi, eventType, mechanism, context);

Using VI_QUEUE in the mechanism parameter specifies a queuing method for the events to be handled. If you use both VI_QUEUE and one of the mechanisms listed above, notification of events will be sent to both locations. See Using the Queuing Method for more information.

Parameter	Description
vi	The session on which the handler will be installed.
eventType	The type of event to enable.
mechanism	The mechanism by which the event will be enabled. It can be enabled in several different ways. You can use VI_HNDLR in this parameter to specify that the installed handler will be called when the event occurs. Use VI_SUSPEND_HNDLR in this parameter, which puts the events in a queue and waits to call the installed handlers until viEnableEvent is called with VI_HNDLR specified in the mechanism parameter. When viEnableEvent is called with VI_HNDLR specified, the handler for each queued event will be called.
context	Not used in VISA 1.0. Use VI_NULL.

Example: Enabling a Hardware Trigger Event

This example illustrates enabling a hardware trigger event.

viInstallHandler(vi, VI_EVENT_TRIG, my_handler,&addr);
viEnableEvent(vi, VI_EVENT_TRIG, VI_HNDLR, VI_NULL);

The VI_HNDLR mechanism specifies that the handler installed for VI_EVENT_TRIG will be called when a hardware trigger occurs.

If you specify VI_ALL_ENABLE_EVENTS in the eventType parameter, all events that have previously been enabled on the specified session will be enabled for the mechanism specified in this function call.

Use the viDisableEvent function to stop servicing the event specified.

Example: Trigger Callback

This sample program installs an event handler and enables the trigger event. When the event occurs, the installed event handler is called. This program is intended to show specific VISA functionality and does not include error trapping. Error trapping, however, is good programming practice and is recommended in your VISA applications. See Trapping Errors for more information.

The evnthdlr.c sample program illustrates installing an event handler to be called when a trigger interrupt occurs and is installed on your system in the ProgrammingSamples subdirectory.

Example: SRQ Callback

This program installs an event handler and enables an SRQ event. When the event occurs, the installed event handler is called. This sample program is intended to show specific VISA functionality and does not include error trapping. Error trapping, however, is good programming practice and is recommended in your VISA applications. See Trapping Errors for more information.

The srqhdlr.c sample program illustrates installing an event handler to be called when an SRQ interrupt occurs and is installed on your system in the ProgrammingSamples subdirectory. .